%% This file is part of Enblend.
%% Licence details can be found in the file COPYING.


\chapter[Bug Reports\commonpart]{\label{sec:bug-reports}%
  \genidx[\rangebeginlocation]{bug!reports}%
  \gensee{problem reports}{bug reports}%
  Bug Reports\commonpart}

\begin{geeknote}
  \noindent Most of this appendix was taken from the \uref{\gnuorgoctave}{Octave} documentation.
\end{geeknote}

Bug reports play an important role in making \App{} and~\OtherApp{} reliable and enjoyable.

\genidx{bug!database at LaunchPad}%
\gensee{LaunchPad!bug database}{bug, database at LaunchPad}%
When you encounter a problem, the first thing to do is to see if it is already known.  To this
end, visit the package's \uref{\launchpadnet}{LaunchPad} bug
\urefval{val:PACKAGE_BUGREPORT}{database}.  Search it for your particular problem.  If it is not
known, please report it.

In order for a bug report to serve its purpose, you must include the information that makes it
possible to fix the bug.

\propername{Eric Steven~Raymond} and \propername{Rick Moen} have collected some extensive wisdom
on \uref{\smartquestions}{How To Ask Questions The Smart Way}.


\section[Found a Bug?]{\label{sec:have-you-really-found-a-bug}%
  \genidx{bug!reports!identification of bugs}%
  Have You Really Found a Bug?}

If you are not sure whether you have found a bug, here are some guidelines:

\begin{itemize}
\item
  If \App{} or \OtherApp{} get a fatal signal, for any options or input images, that is a bug.

\item
  If \App{} or \OtherApp{} produce incorrect results, for any input whatever, that is a bug.

\item
  If \App{} or \OtherApp{} produce an error message for valid input, that is a bug.

\item
  If \App{} or \OtherApp{} do not produce an error message for invalid input, that is a bug.
\end{itemize}


\section[How to Report Bugs]{\label{sec:how-to-report-bugs}%
  \genidx{bug!reports!how to}%
  How to Report Bugs}

The fundamental principle of reporting bugs usefully is this: report all the facts.  If you are
not sure whether to state a fact or leave it out, state it.  Often people omit facts because
they think they know what causes the problem and they conclude that some details do not matter.
Play it safe and give a specific, complete example.

Keep in mind that the purpose of a bug report is to enable someone to fix the bug if it is not
known.  Always write your bug reports on the assumption that the bug is not known.

Try to make your bug report self-contained.  If we have to ask you for more information, it is
best if you include all the previous information in your response, as well as the information
that was missing.

To enable someone to investigate the bug, you should include all these things:

\begin{description}\renewcommand{\makelabel}[1]{\textbf{#1}}
\item[Exact Version:] The exact version and configuration of \App.  You can get the data by
  running \app{} with the options \option{--version} and~\option{--verbose} together.  See also
  \sectionName~\fullref{sec:finding-out-details} on how to find out the exact configuration of
  your binary.

\item[Complete and Minimal Set of Images:] A complete yet minimal set of input images that will
  reproduce the bug.  The less images the set contains the faster we can run our tests.  The
  optimum is a set of just two input images.

\item[Small Images:] Strive for small images, where images up to 1500\classictimes 1000~pixels
  qualify as small.

\item[Environment:] The type of machine you are using, and the operating system name and its
  version number.

\item[Prior Modifications:] A complete list of any modifications you have made to the source.
  Be precise about these changes.  Show a \command{diff}-generated delta for them.

\item[Odd Workflow:] Details of any other deviations from the standard procedure for installing
  \App{} and \OtherApp{}.

\item[Exact Command Line:] The exact command line you use to call \App{} or \OtherApp{}, which
  then triggers the bug.

  Examples:

  \begin{terminal}
    \$ \squiggle/local/bin/enblend -v \bslash \\
    ~~~~--fine-mask \bslash \\
    ~~~~--optimizer-weights=3:2 \bslash \\
    ~~~~--mask-vectorize=12.5\% \bslash \\
    ~~~~image-1.png image-2.png
  \end{terminal}

  or:

  \begin{terminal}
    \$ /local/bin/enfuse \bslash \\
    ~~~~--verbose \bslash \\
    ~~~~--exposure-weight=0 --saturation-weight=0 --entropy-weight=1 \bslash \\
    ~~~~--gray-projector=l-star \bslash \\
    ~~~~--entropy-cutoff=1.667\% \bslash \\
    ~~~~layer-01.ppm layer-02.ppm layer-03.ppm
  \end{terminal}

  \appidx{Hugin}%
  \appidx{ImageFuser}%
  If you call \App{} or \OtherApp{} from within a \acronym{GUI} like, for example,
  \uref{\huginsourceforgenet}{Hugin} or \uref{\imagefuser}{ImageFuser} by \propername{Harry van
    der Wolf}, copy\&paste or write down the command line that launches \App{} or \OtherApp{}.

\item[Bug Description:] A description of what behavior you observe that you believe is
  incorrect.  For example, ``The application gets a fatal signal,'' or, ``The output image
  contains black holes.''

  Of course, if the bug is that the application gets a fatal signal, then one cannot miss it.
  But if the bug is incorrect output, we might not notice unless it is glaringly wrong.
\end{description}


\section[Sending Patches]{\label{sec:sending-patches}%
  \genidx{bug!reports!sending patches}%
  Sending Patches for \App{} or \OtherApp{}}

If you would like to write bug fixes or improvements for \App{} or \OtherApp{}, that is very
helpful.  When you send your changes, please follow these guidelines to avoid causing extra work
for us in studying the patches.  If you do not follow these guidelines, your information might
still be useful, but using it will take extra work.

\begin{itemize}
\item
  Send an explanation with your changes of what problem they fix or what improvement they bring
  about.  For a bug fix, just include a copy of the bug report, and explain why the change fixes
  the bug.

\item
  Always include a proper bug report for the problem you think you have fixed.  We need to
  convince ourselves that the change is right before installing it.  Even if it is right, we
  might have trouble judging it if we do not have a way to reproduce the problem.

\item
  Include all the comments that are appropriate to help people reading the source in the future
  understand why this change was needed.

\item
  Do not mix together changes made for different reasons.  Send them individually.

  If you make two changes for separate reasons, then we might not want to install them both.  We
  might want to install just one.

\item
  Use the version control system to make your diffs.  Prefer the
  \uref{\wikipediadiffunifiedformat}{unified diff} format: \code{hg diff --git --unified=8}.

\item
  You can increase the probability that your patch gets applied by basing it on a recent
  revision of the sources.
\end{itemize}

\genidx[\rangeendlocation]{bug!reports}


%%% Local Variables:
%%% fill-column: 96
%%% End:
